Skip to main content

ListAuditLogsV1

A GET request that retrieves a list of your organization's audit logs. The endpoint is https://api.aware.work/external/system/auditlogs/v1.

Access​

To access this operation, your API token must have one of the following permissions:

For more information, see the API token documentation.

Request Format​

Parameters​

None of the below parameters are required. However, they can assist you in selecting the data you're looking for much more easily and efficiently than paging through all logs depending on your use-case.

To use filters, you must send the filter URL parameter along with any filters you would like to apply. Below is an exhaustive list of the filters you can use:

ParameterRequiredDescriptionTypeFormat / Options
filter=
startDate:<date>,
endDate:<date>		NoReturn audit log entries from start date through end date

Default is prior 15 days through today if neither startDate nor endDate is specified

Date is UTC		stringdate arguments must be in format yyyy-MM-dd
filter=
startDate:<date>		NoReturn audit log entries from start date through today

Date is UTC		stringdate arguments must be in format yyyy-MM-dd
filter=endDate:<date>NoReturn audit log entries from 90 days before end date through end date

Date is UTC		stringdate arguments must be in format yyyy-MM-dd
limit=<count>NoReturn <count> log entries per page

Default is 200		intinteger between 1 and 500 inclusive
offset=<offset>NoReturn log entries starting at page <offset>

Default is 1		intInteger greater than or equal to 1

Query​

Below is the request in its most basic form. See request samples for more advanced query examples.

curl -X GET --location "https://api.aware.work/external/system/auditlogs/v1" \
    -H "X-Aware-Api-Key: ${API_TOKEN}" \

Response Format​

If there are one or more results, the endpoint returns an HTTP 200 status and a response body whose general format looks something like this:

{
    "value": {
        "totalCount": 139653,
        "auditLogData": [
            {
                "tenantId": "ae064f55-d69a-4434-9df8-7e07969cb1d9",
                "userName": "Bob Smith",
                "emailAddress": "bob.smith@gmail.com",
                "sourceIp": "SourceIp",
                "dateTime": {
                    "seconds": 1677165626,
                    "nanos": 734826000
                },
                "auditName": "System",
                "actionName": "Logged out due to session inactivity",
                "actionSummary": "Logged out due to session inactivity",
                "additionalInfoJson": ""
            },
            {
                "tenantId": "ae064f55-d69a-4434-9df8-7e07969cb1d9",
                "userName": "Michelle Walters",
                "emailAddress": "michelle.walters@microsoft.com",
                "sourceIp": "68.238.179.230",
                "dateTime": {
                    "seconds": 1677165099,
                    "nanos": 624461000
                },
                "auditName": "System",
                "actionName": "Logged into Aware",
                "actionSummary": "Logged into Aware",
                "additionalInfoJson": "{\"roles\": [ \"Manager\"],\"lastLogin\": \"2/28/2023\"}"
            },
        .......<MORE_RESULTS DEPENDING ON LIMIT>
        ]
    },
    "statusCode": 200
}

where:

  • totalCount is the total number of audit log entries for your organization that match the filter criteria.

  • tenantId is the unique internal ID for your organization’s data.

  • userName is the name of the active user when the log entry was recorded.

  • emailAddress is the active user’s email address.

  • sourceIp is the IP address of the source of the request, if known.

  • dateTime is the time the log entry was recorded:

  • seconds is the Unix epoch time. For example, when converted to a human-readable format, 1677165626 is 15:20:26 PM on February 23, 2023, UTC time.

  • nanos is the number of nanoseconds, after that date/time, that the log entry was recorded.

  • auditName is a text string that identifies the app or component that recorded it.

  • actionName is a name for the action that’s being logged.

  • actionSummary is a brief description of the action that’s being logged.

  • additionalInfoJson is optional, action-specific information that can be included in JSON format. If there is none, contains an empty string ( "" ).

  • statusCode is the HTTP status code that is returned from the GET request.

If there are no results, the endpoint returns an HTTP 200 status and a response body having the same high-level structure as above, but the results element contains an empty array as shown below:

{
    "value": {
        "totalCount": 0,
        "auditLogData": []
    },
    "statusCode": 200
}

Request Samples​

Get audit logs for a given range of days​

curl -X GET --location "https://api.aware.work/external/system/auditlogs/v1?\
    filter=startDate:2023-03-01,endDate:2023-03-15" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get audit logs created on or after a given date​

curl -X GET --location "https://api.aware.work/external/system/auditlogs/v1?\
    filter=startDate:2023-03-01" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get audit logs for the 90-day period from 2022-12-31 to 2023-03-31​

curl -X GET --location "https://api.aware.work/external/system/auditlogs/v1?\
    filter=startDate:2023-03-01" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get the most recent 100 log entries for the past 90 days​

curl -X GET --location "https://api.aware.work/external/system/auditlogs/v1?\
    limit=100" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Retrieve the second page for a request that cannot fit all results in a single page​

curl -X GET --location "https://api.aware.work/external/system/auditlogs/v1?\
    offset=2" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"